Posicube Document Parser API 연동 가이드

공통 연동 규격

• Base URL: https://playground-api.posicube.com

• 인증 (Authentication): X-Api-Key 헤더에 발급받은 API Key 전달

• Content-Type: 파일 업로드를 위해 반드시 multipart/form-data 사용

Multipart Request 전송 시 주의사항

API 요청 시 file(이미지/PDF) 파트와 함께, request 파트에 JSON 설정값을 담아 전송합니다.

★ 가장 중요한 점: request 파트 전송 시 해당 파트의 Content-Type을 반드시 application/json****으로 명시해야 합니다. 기본값으로 보내면 500 파싱 오류가 발생합니다.

---

1. Schema 자동 추출 API

파일을 업로드하여 문서에서 추출하려는 항목의 구조(Schema)를 자동으로 생성하는 기능입니다.

Endpoint

POST 
/external/v1/extract-schema-tasks

Request Parts (multipart/form-data)

Part Name	Type	Description
file ⚠️	File (Binary)	스키마를 추출할 문서 파일 (png, jpg, pdf 등)
request ⚠️	JSON String	JSON 형식의 스키마 추출 옵션※ Content-Type: application/json 필수

Request JSON Fields

Field Name	Type	Description
customPrompt	String (optional)	스키마 추출을 위한 추가 지시사항 (빈 문자열 가능)
llmProvider	String (optional)	[지원 예정] 추후 지원될 모델 선택을 위한 필드입니다
llmModel	String (optional)	[지원 예정] 추후 지원될 모델 선택을 위한 필드입니다

extract_schema.py

import requests
import json

url = "https://playground-api.posicube.com/external/v1/extract-schema-tasks"
headers = {"X-Api-Key": "YOUR_API_KEY_HERE"}

# request JSON 구성
request_data = json.dumps({"customPrompt": ""})

# Multipart 구성 (request 파트의 Content-Type 명시)
with open("test.png", "rb") as img_file:
    files = [
        ("file", ("test.png", img_file, "image/png")),
        ("request", (None, request_data, "application/json"))
    ]

    response = requests.post(url, headers=headers, files=files)
    print("Status Code:", response.status_code)
    print(response.json())

cURL

curl -X POST "
https://playground-api.posicube.com/external/v1/extract-schema-tasks
" \
     -H "X-Api-Key: YOUR_API_KEY_HERE" \
     -F "file=@test.png;type=image/png" \
     -F "request={\"customPrompt\": \"\"};type=application/json"

Response Example (200 OK)

{
  "code": "200",
  "message": "operation success",
  "data": {
    "id": 269,
    "taskId": "90e004ef-c068-4faf-b2df-c62440864f23",
    "documentId": 835,
    "status": "COMPLETED",
    "output": "{\"taskId\":\"90e004ef-c068...\",\"schema\":[{\"item\":\"docTitle\",\"description\":\"문서제목\",\"type\":\"string\",\"is_array\":false,\"children\":[]}]}",
    "errorMessage": null,
    "startedAt": "2026-02-26T14:24:03",
    "completedAt": "2026-02-26T14:24:21"
  }
}

응답 결과 해석

• data.output 파싱: 응답의 data.output 값은 이스케이프된 **JSON String(문자열)**입니다. 클라이언트에서 한 번 더 JSON 파싱(Unmarshalling)을 수행해야 객체 형태로 사용할 수 있습니다.
• 추출된 Schema 활용: 파싱된 결과 내부의 schema 배열은 문서 내 각 항목의 식별자(item), 설명(description), 데이터 타입 등을 정의합니다. 이 배열을 아래 데이터 추출 API의 schemaObj에 전달하여 실제 값을 추출합니다.

---

2. 데이터 추출 API

업로드한 이미지(문서)와 구조화된 스키마(Schema)를 바탕으로, 각각의 키(Key)에 대해 해당하는 값(Value)과 위치 좌표를 추출하는 기능입니다.

Endpoint

POSt 
/external/v1/extract-tasks

Request Parts (multipart/form-data)

Part Name	Type	Description
file ⚠️	File (Binary)	추출할 대상 문서 파일
request ⚠️	JSON String	추출 옵션 및 Schema 구조를 담은 JSON 데이터

Request JSON Fields

Field Name	Type	Description
schemaObj ⚠️	Object (Array)	추출할 데이터 스키마가 정의된 배열 (API 1의 결과물 활용)
customPrompt	String (optional)	추가 추출 지시사항
llmProvider	String (optional)	[지원 예정] 추후 지원될 모델 선택을 위한 필드입니다
llmModel	String (optional)	[지원 예정] 추후 지원될 모델 선택을 위한 필드입니다

extract_data.py

import requests
import os

url = "https://playground-api.posicube.com/external/v1/extract-tasks"
headers = {"X-Api-Key": "YOUR_API_KEY_HERE"}

pdf_path = "/path/to/document.pdf"
request_json_path = "/path/to/request.json"

# request.json (schemaObj 등이 포함된 파일) 읽기
with open(request_json_path, "r", encoding="utf-8") as f:
    schema_content = f.read()

with open(pdf_path, "rb") as file_data:
    files = [
        ("file", (os.path.basename(pdf_path), file_data, "application/pdf")),
        ("request", (None, schema_content, "application/json"))
    ]

    response = requests.post(url, headers=headers, files=files)
    print("Status Code:", response.status_code)
    print(response.json())

cURL

curl --location 'https://playground-api.posicube.com/external/v1/extract-tasks' \
     --header 'X-Api-Key: YOUR_API_KEY_HERE' \
     --form 'file=@"/path/to/document.pdf";type=application/pdf' \
     --form 'request=@/path/to/request.json;type=application/json'

Response Example (200 OK)

{
  "code": "200",
  "message": "operation success",
  "data": {
    "id": 469,
    "taskId": "7fb29c24-39f4-469a-8872-26300c0b20f4",
    "status": "COMPLETED",
    "output": "{\"taskId\":\"7fb29c24...\",\"pages\":[{\"pageIdx\":1,\"details\":{\"docTitle\":{\"text\":\"재직증명서\",\"bbox\":[0.348,0.165,0.657,0.209]}}}]}",
    "errorMessage": null,
    "startedAt": "2026-02-26T14:38:05",
    "completedAt": "2026-02-26T14:38:31"
  }
}

응답 결과 해석

• data.output 파싱: 여기서도 data.output은 JSON 문자열입니다.
• 데이터 추출 값 확인: JSON 파싱 후, pages[].details 내부에 요청한 스키마(예: docTitle)에 맞게 데이터가 매핑되어 있습니다.
• text와 bbox: 추출된 각 필드마다 인식된 문자열 값인 text와, 이미지 상의 바운딩 박스(영역 좌표) 정보인 bbox가 배열 형태로 제공됩니다.

---

3. 문서 파싱 API

이미지의 문서를 분석하여 마크다운(md), HTML, 일반 텍스트(text) 포맷으로 추출하는 기능입니다.

Endpoint

POST 
/external
/v1/parse-tasks

Request Parts (multipart/form-data)

Part Name	Type	Description
file ⚠️	File (Binary)	파싱할 대상 문서 파일
request ⚠️	JSON String	JSON 형식의 파싱 옵션

Request JSON Fields

Field Name	Type	Description
contentFormat ⚠️	String	결과 포맷. 지원값:md[지원 예정] html[지원 예정] text
encodingOption ⚠️	Boolean	true인 경우 이미지나 테이블의 객체가 base64 인코딩되어 포함되고, false일 경우 좌표값만 반환되는 옵션입니다.※ 누락 시 HTTP 400 에러 발생
llmProvider	String (optional)	[지원 예정] 추후 지원될 모델 선택을 위한 필드입니다
llmModel	String (optional)	[지원 예정] 추후 지원될 모델 선택을 위한 필드입니다

parse_document.py

import requests
import json

url = "https://playground-api.posicube.com/external/v1/parse-tasks"
headers = {"X-Api-Key": "YOUR_API_KEY_HERE"}

# 변환 포맷 및 인코딩 옵션(필수) 지정
request_json = json.dumps({
    "contentFormat": "md",
    "encodingOption": False
}, ensure_ascii=False)

with open("test.png", "rb") as img_file:
    files = [
        ("file", ("test.png", img_file, "image/png")),
        ("request", (None, request_json, "application/json"))
    ]

    response = requests.post(url, headers=headers, files=files)
    print("Status Code:", response.status_code)
    print(response.json())

cURL

curl -X POST "https://playground-api.posicube.com/external/v1/parse-tasks" \
     -H "X-Api-Key: YOUR_API_KEY_HERE" \
     -F "file=@test.png;type=image/png" \
     -F "request={\"contentFormat\": \"md\", \"encodingOption\": false};type=application/json"

Response Example (200 OK)

{
  "code": "200",
  "message": "operation success",
  "data": {
    "id": 1,
    "taskId": "task-uuid-12345",
    "status": "COMPLETED",
    "output": "{\"totalPages\":3,\"content\":\"# 파싱된 문서 내용\\n요청한 포맷(예: 마크다운)에 따라 문서의 텍스트가 추출됩니다.\"}",
    "errorMessage": null,
    "startedAt": "2026-02-26T12:00:00",
    "completedAt": "2026-02-26T12:00:05"
  }
}

응답 결과 해석

• data.output 파싱: 문자열로 응답된 output 필드를 JSON 형태로 변환합니다.
• 문서 전체 내용: 변환된 객체 내부의 content 필드에 문서 전체의 내용이 담겨 있습니다.
• 지정한 contentFormat에 맞춰 마크다운 문법, HTML 태그, 혹은 일반 텍스트 형태로 제공되며, encodingOption 값에 따라 본문 내 이미지/표의 형태(Base64 혹은 좌표)가 달라집니다.

---